perf(cli): load the Effect terminal runtime lazily to restore cold-start time - #530

Summary

#505 made runCli build makeScopedEffectRuntime(nodeCliServices) at the composition root, before Commander parsed argv. That loaded effect, effect/Terminal, effect/Stdio, and the two @effect/platform-node-shared layers on every invocation, including --version and --help: cold start went from ≈60 ms to ≈300 ms. This PR keeps the Terminal/Stdio adoption for command output and loads the runtime lazily, on a command's first write. create-agent-bundle gets the same split (its --help had gone ≈40 → ≈70 ms across #501/#505).

Where the time went

Measured in-process on rc.112 (node v22.23.2, unbundled effect in node_modules):

Module loading is the whole cost; runtime/layer construction is noise, so memoizing the runtime buys nothing and the fix is to not load the modules for invocations that never write through them.

What changed

• packages/agent-bundle/src/effect/cli-runtime.ts (new): makeCliTerminal(services) — the CLI composition root (makeScopedEffectRuntime(nodeCliServices) behind Promise-shaped display / writeStdout / writeStderr / close). The only module that pulls Effect into the CLI process.
• packages/agent-bundle/src/cli.ts: imports cli-runtime.ts type-only and loads it with import() on the first command write (cliTerminal()), the same pattern that already keeps ./api.ts off the trivial path. Commander's own text (--help, --version, argv errors) is written synchronously through configureOutput to CliOutput.argvText (default: the process streams) — the queue-and-replay through Terminal.display is gone; Commander only writes before aborting parsing, so nothing interleaves. The runtime closes in finally only if a command built it; a foreground dev session still keeps it until the session closes.
• packages/create-agent-bundle/src/index.ts → src/scaffold-cli.ts (new): runCli parses flags and writes --help / flag errors synchronously to CliStreams, then dynamically imports scaffold-cli.ts (the NodeServices.layer root, the scaffold program, Clack). Rslib splits it into dist/scaffold-cli.js (447.5 kB); the argv layer is 10.8 kB.
• Tests: tests/support/cli-terminal.ts captures the argv sinks too; cli-text.test.ts runs runCli with capture streams. New proof in packages/agent-bundle/tests/cli.test.ts: the built CLI runs under a module.registerHooks resolve recorder (tests/support/record-module-loads.mjs) and the test fails if --version, --help, or an argv error resolves any effect / @effect/platform-node-shared URL (and checks a real command does).
• docs/effect-conventions.md: Terminal/Stdio section rewritten around the lazy root, the argv-text exception, the module-load vs construction breakdown, and the re-measured numbers; scaffolder boundary paragraph and the module table row updated.

Before / after

Median wall time, built bin/*.js, Node v22.23.2, same machine, back-to-back runs (node -e 0 ≈28 ms). The pre-#505 column is e0ae9f0ca^ built from source.

Module set resolved by --version is now byte-identical to pre-#505 (commander + 9 dist/*.js chunks, no effect).

"Commander's help through Terminal vs a sync writer": the existing path is the Terminal path, and any Effect import costs ≥ 240 ms, so there is no lazy variant of it that meets the budget; the sync writer is the pre-#505 path restored.

Review status

• CI: all checks green on head 70bb48846.
• Automated review (chatgpt-codex-connector): reviewed 8bba903ac; one P1 thread — append the (#PR) suffix to the changeset — addressed in 70bb48846 (changeset text only; no code changed). Head 70bb48846 is not re-reviewed; per the task's instructions no PR comments are posted, so this note stands in for the thread reply and the re-review request.